/*
 * Course:    CS 590 Web Services
 * Semseter:  Spring 2009
 * Professor: Sedlemeyer
 * Project:   CHEAT (Code Help Educational Assignment Tool)
 * Due Date:  May 1, 2009
 * Team:      Sarcasm
 *            (Baker, Jason; Mitchell, Robin; Shie, Keith)
 */
package cheat.assignment;

import cheat.authentication.InsufficientAccessException;
import cheat.authentication.InvalidSessionException;
import cheat.entities.Person;
import edu.ipfw.cs590.cheat.services.AssignmentWrapper;
import java.util.List;
import javax.ejb.Remote;

/**
 * Provides the remote interface to the AssignmentManagerBean.
 *
 * The assignment manager contains the functionality related to
 * assignment management.
 *
 * @author Keith Shie
 */
@Remote
public interface AssignmentManagerRemote {

  /**
   * Submit an assignment to the assignment sharing system.
   *
   * <p>Only FACULTY are permitted to submit assignments.</p>
   *
   * <p>Asignments archives are separated into three parts; the metadata,
   * the student files, and the faculty files.</p>
   *
   * <p>Metadata is stored into aa collection of entities to facilitate
   * searching.</p>
   *
   * <p>Student only files are placed into an student archive entity. and
   * likewise for the faculty files.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentZip bytes of zip file containing the assignment archive.
   *
   * @return uuid of the newly added assignment.
   *
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   * @throws InvalidAssignmentArchiveException
   */
  int submitAssignment( int sessionId, byte[] assignmentZip ) throws InvalidSessionException, InsufficientAccessException,
                      InvalidAssignmentArchiveException;


  /**
   * Obtain the metadata associated with the specified assignmentUuid.
   *
   * @param assignmentUuid Unique id of the assignment for which metadata is
   * required.
   * @return An assignment's metadata object wrapped so as to allow it to
   * be returned to the caller via Java Serialization.  The contents of the
   * wrapped object are a byte[] containing the bytes of the metadata file.
   * @throws cheat.authentication.InvalidSessionException
   * @throws AssignmentNotFoundException
   */
  public AssignmentWrapper getAssignmentMeta( int assignmentUuid ) throws InvalidSessionException, AssignmentNotFoundException;


  /**
   * Extract the assignment specified by <code>assignmentUuid</code>.
   *
   * <p>Requests from users with FACULTY access recieve all content.
   * STUDENT's do not receive content specifically designated for
   * FACULTY.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentUuid Unique id of the assignment for which metadata is
   * required.
   *
   * @return bytes of zip file containing the assignment archive.
   *
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.assignment.AssignmentNotFoundException
   */
  byte[] getAssignment( int sessionId, int assignmentUuid ) throws InvalidSessionException, AssignmentNotFoundException;


  /**
   * Remove the specified assignment from the system.
   *
   * <p>Assignments are logically removed from the system so as to
   * preserve referential integrity.  An assignment logically removed
   * will no longer be returned via queries through the system.</p>
   *
   * <p>Only ADMIN and FACULTY can remove an assignment.</p>
   *
   * <p>ADMIN can remove any assignment.</p>
   *
   * <p>FACULTY can only remove an assignment which they are either an
   * owner or an author.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentUuid Unique id of the assignment for which metadata is
   * required.
   *
   * @return true if the assignment has been removed.
   *
   * @throws InvalidSessionException
   * @throws InsufficientAccessException
   * @throws AssignmentNotFoundException
   */
  boolean removeAssignment( int sessionId, int assignmentUuid ) throws InvalidSessionException,
                                                                       InsufficientAccessException,
                                                                       AssignmentNotFoundException;


  /**
   * Replace the specified assignment in the system.
   *
   * <p>The previous assignment is logically removed from the system
   * so as to preserve referential integrity.  An assignment logically
   * removed will no longer be returned via queries through the system.</p>
   *
   * <p>Only ADMIN and FACULTY can replace an assignment.</p>
   *
   * <p>ADMIN can replace any assignment.</p>
   *
   * <p>FACULTY can only replace an assignment which they are either an
   * owner or an author.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param priorAssignmentUuid Unique id of the assignment for which metadata is
   * required.
   *
   * @param assignmentZip bytes of zip file containing the assignment archive.
   *
   * @return the new uuid.
   *
   * @throws InvalidSessionException
   * @throws InsufficientAccessException
   * @throws AssignmentNotFoundException
   * @throws InvalidAssignmentArchiveException
   */
  int replaceAssignment( int sessionId, int priorAssignmentUuid, byte[] assignmentZip ) throws InvalidSessionException,
                                                                                            InsufficientAccessException,
                                                                                            AssignmentNotFoundException,
                                                                                            InvalidAssignmentArchiveException;


  /**
   * Search for assignments which have the specified programming
   * language.
   *
   * @param language the program language to search for.
   *
   * @return list of wrapped assignments matching the criteria.
   */
  List<AssignmentWrapper> findByLanguage( String language );


  /**
   * Search for assignments which have the specified keywords.
   *
   * @param keyword the list of keywords to search for.
   *
   * @return list of wrapped assignments matching the criteria.
   */
  List<AssignmentWrapper> findByKeyword( List<String> keyword );


  /**
   * Search for assignments which have the specified course.
   *
   * @param course the course to search for.
   *
   * @return list of wrapped assignments matching the criteria.
   */
  List<AssignmentWrapper> findByCourse( String course );


  /**
   * Search for assignments which have the specified email.
   *
   * @param email the author's email to search for.
   *
   * @return list of wrapped assignments matching the criteria.
   */
  List<AssignmentWrapper> findByAuthor( String email );


  /**
   * Get the history of an assignment.
   *
   * @param assignmentUuid Unique id of the assignment for which history is
   * desired.
   *
   * @return a list of the ancestors of the specified assignment.<p><i>Does include the specified assignment.</i>  Will
   * return a list ith no elements if there is no ansectry.</p>
   * @throws cheat.assignment.AssignmentNotFoundException
   */
  List<AssignmentWrapper> getAssignmentHistory( int assignmentUuid ) throws AssignmentNotFoundException;


  /**
   * Merge the specified archive with an existing assignment within the assignment sharing system.
   *
   * <p>Only an assignment owner can perform this operation.</p>
   *
   * <p>files within the mergeZip archive overwrite files within the existing archive with the
   * same name.  New files within the mergeZip archive are added the the existing assignment.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentUuid Unique id of the existing assignment.
   *
   * @param mergeZip bytes of zip file containing the archive to be merged.
   *
   * @see #submitAssignment
   *
   * @throws cheat.assignment.AssignmentNotFoundException
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   * @throws cheat.assignment.InvalidAssignmentArchiveException
   */
  void mergeAssignment( int sessionId, int assignmentUuid, byte[] mergeZip ) throws AssignmentNotFoundException,
                                                                                    InvalidSessionException,
                                                                                    InsufficientAccessException,
                                                                                    InvalidAssignmentArchiveException;


  /**
   * Get the list of files contained within this assignment.
   *
   * <p>Requests from users with FACULTY access recieve all content.
   * STUDENT's do not receive content specifically designated for
   * FACULTY.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentUuid Unique id of the assignment for which the files list is
   * desired.
   *
   * @return a list of files contained within this assignment.
   *
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.assignment.AssignmentNotFoundException
   * @throws cheat.authentication.InsufficientAccessException
   */
  List<String> getAssignmentFileList( int sessionId, int assignmentUuid ) throws InvalidSessionException,
                                                                                 AssignmentNotFoundException,
                                                                                 InsufficientAccessException;


  /**
   * Remove files from the assignment.
   *
   * <p>Only an assignment owner can perform this operation.</p>
   *
   * @param sessionId Id of UserSession to use to determine access level.
   *
   * @param assignmentUuid Unique id of the assignment for which the files list is
   * desired.
   *
   * @param removalList list of files to be removed.
   *
   * @throws cheat.assignment.AssignmentNotFoundException
   * @throws cheat.authentication.InvalidSessionException
   * @throws cheat.authentication.InsufficientAccessException
   */
  void removeAssignmentFile( int sessionId, int assignmentUuid, List<String> removalList ) throws AssignmentNotFoundException,
                                                                                                  InvalidSessionException,
                                                                                                  InsufficientAccessException;


  /**
   * Get the owner of an assignment.
   *
   * @param assignmentUuid Unique id of the assignment for which the files list is
   * desired.
   *
   * @return email address for the assignment's owner.
   *
   * @throws cheat.assignment.AssignmentNotFoundException
   */
  String getOwner( int assignmentUuid ) throws AssignmentNotFoundException;
}
